﻿@page "/docs/components/validation"

<Seo Canonical="/docs/components/validation" Title="Blazorise Validation Component" Description="Learn to use and work with the Blazorise Validation components, which are used to provide simple form validation for Blazorise input components." />

<DocsPageTitle Path="Components/Validation">
    Blazorise Validation component
</DocsPageTitle>

<DocsPageLead>
    The <Code>Validation</Code> component allows you to verify your data, helping you find and correct errors.
</DocsPageLead>

<DocsPageParagraph>
    Validation components are used to provide simple form validation for Blazorise input components.
</DocsPageParagraph>

<DocsPageParagraph>
    The basic structure for validation component is:
</DocsPageParagraph>

<UnorderedList>
    <UnorderedListItem>
        <Paragraph>
            <Code Tag>Validations</Code> container for all validations, it can contain multiple <Code>Validation</Code> components.
        </Paragraph>
        <UnorderedList>
            <UnorderedListItem>
                <Paragraph>
                    <Code Tag>Validation</Code> component that contains the validation logic.
                </Paragraph>
                <UnorderedList>
                    <UnorderedListItem>
                        <Paragraph>
                            <Code Tag>Feedback</Code> component that displays the validation message.
                        </Paragraph>
                        <UnorderedList>
                            <UnorderedListItem>
                                <Paragraph>
                                    <Code Tag>ValidationSuccess</Code> success message.
                                </Paragraph>
                            </UnorderedListItem>
                            <UnorderedListItem>
                                <Paragraph>
                                    <Code Tag>ValidationError</Code> error message.
                                </Paragraph>
                            </UnorderedListItem>
                            <UnorderedListItem>
                                <Paragraph>
                                    <Code Tag>ValidationNone</Code> message when nothing has happened.
                                </Paragraph>
                            </UnorderedListItem>
                        </UnorderedList>
                    </UnorderedListItem>
                </UnorderedList>
            </UnorderedListItem>
            <UnorderedListItem>
                <Paragraph>
                    <Code Tag>ValidationSummary</Code> lists all error messages
                </Paragraph>
            </UnorderedListItem>
        </UnorderedList>
    </UnorderedListItem>
</UnorderedList>

<DocsPageParagraph>
    For the most part you will need to use just the <Code Tag>Validation</Code> component along
    with <Code Tag>ValidationSuccess</Code> and <Code Tag>ValidationError</Code>. By default every validation
    will run automatically when input value changes. You must set the <Code>Validator</Code> event handler where you can
    define the validation rules and return the validation result.
</DocsPageParagraph>

<DocsPageSubtitle>
    Examples
</DocsPageSubtitle>

<DocsPageSection>
    <DocsPageSectionHeader Title="Validating using Methods handlers">
        <Paragraph>
            Method handlers are the easiest and quickest way to validate fields. Therefore, we give you a set of predefined validation handlers that can be accessed through the  <Code>ValidationRule</Code> helpers class and assigned to the <Code>Validator</Code> parameter.
        </Paragraph>
        <Paragraph>
            Apart from using the pre-built handler methods, you can also create your own. For example, you can see the custom <Code>ValidateEmail</Code> handler in the following code-snippet.
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <BasicValidationExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="BasicValidationExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader>
        The same structure is for all <Code>Edit</Code> components(check, radio, select, etc). Note that for some components
        there are some special rules when defining the validation structure. For example for <Code>Check</Code> you must use
        <Code>ChildContent</Code> tag along with the <Code>Feedback</Code> tag. This is a limitation in Blazor, hopefully it
        will be fixed in the future.
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="ValidationFeedbackExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Validating using Data Annotations">
        To use data annotations with Blazorise you must combine both <Code>Validation</Code> and the <Code>Validations</Code>
        components. The <Code>Validations</Code> component will act as a group for a fields used inside of <Code>Validation</Code>
        component. To make it all work you must meet two requirements:
        <OrderedList>
            <OrderedListItem>
                <Code>Validations</Code> component must contain reference to the validated POCO through the <Code>Model</Code> parameter.
            </OrderedListItem>
            <OrderedListItem>
                Input component must bind to the model field through the <Code>@@bind-{Value}</Code>(i.e. <Code>@@bind-Text</Code>)
            </OrderedListItem>
        </OrderedList>
        After those two requirements are met the Blazorise will have enough information to know how to use data annotations.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <DataAnnotationValidationExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="DataAnnotationValidationExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Validating using Pattern">
        If you want to validate input by using regular expression instead of <Code>Validator</Code> handlers you can
        use <Code>Pattern</Code> patameter. Components that supports pattern attribute are
        <Code>TextEdit</Code>, <Code>NumericEdit</Code> and <Code>DateEdit</Code>.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <PatternValidationExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="PatternValidationExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Async validation">
        In case you need to run validation using the external source or rest API, we also support async validation.
        The process is similar to regular validator. You just need to define awaitable handler using
        the <Code>AsyncValidator</Code> parameter.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <AsyncValidationExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="AsyncValidationExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Manual validation">
        Sometimes you don't want to do validation on every input change. In that case you use <Code Tag>Validations</Code> component
        to group multiple validations and then run the validation manually.
        <br />
        <br />
        In this example you can see how the <Code Tag>Validations</Code>component is used to enclose multiple validation
        components and the <Code>Mode</Code> attribute is set to <Code>Manual</Code>. Validation is executed only when
        clicked on submit button.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <ManualValidationExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="ManualValidationExample" />
</DocsPageSection>

<DocsPageSubtitle>
    Localization
</DocsPageSubtitle>

<DocsPageParagraph>
    If you want to localize your validation messages, we got you covered. Blazorise will provide you with an API
    and all the required information needed for you to make localization. This is done through the <Code>MessageLocalizer</Code> API.
    But before you use it we need to break it down a little so you can understand it better how it works.
</DocsPageParagraph>

<DocsPageParagraph>
    A <Code>MessageLocalizer</Code> is fairly straight forward. It accepts two parameters and returns a string. It's
    signature is as following <Code>string Localize(string message, IEnumerable&lt;string&gt; arguments)</Code>.
</DocsPageParagraph>

<DocsPageParagraph>
    Where:
</DocsPageParagraph>

<UnorderedList>
    <UnorderedListItem>
        <Code>format</Code> raw validation message
    </UnorderedListItem>
    <UnorderedListItem>
        <Code>arguments</Code> list of arguments or values for populating the message
    </UnorderedListItem>
</UnorderedList>

<DocsPageParagraph>
    So now that you know what the API consist of, we need to talk what is the content of the API. And the most important
    is the <Code>message</Code> parameter. Each message value will be represented as a raw message in the form before
    the actual message was formatted.
</DocsPageParagraph>

<DocsPageParagraph>
    For example if you have a <Code>[Required]</Code> attribute set on your model field, this message will be
    <Code>"The {0} field is required."</Code>. And the <Code>arguments</Code> will contain all the
    values needed to populate the placeholders inside of the message.
</DocsPageParagraph>

<DocsPageSection>
    <DocsPageSectionHeader Title="Example">
        For the basic example we're going to use <Code>MessageLocalizer</Code> directly on a <Code>Validation</Code> component.
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="LocalizationValidationExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Global Options">
        Setting the <Code>MessageLocalizer</Code> on each <Code>Validation</Code> is a good for approach if you want
        to control every part of your application. But a more practical way is to define it globally. If you remember
        from the Start Guide, we already have <Code>Validation</Code> defined in our application startup so we just need
        to modify it a little.
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="GlobalLocalizationExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Validation summary">
        <Paragraph>
            Sometimes you don't want to show error messages under each field. In those situations you can
            use <Code>ValidationSummary</Code> component. Once placed inside of Validations it will show
            all error messages as a bullet list.
        </Paragraph>
        <Paragraph>
            <Strong>Note:</Strong> The <Code>ValidationSummary</Code> component name conflicts with the
            built-in <Code>Microsoft.AspNetCore.Components.Forms.ValidationSummary</Code> from Blazor.
            If you are using both in the same project, reference Blazorise's version explicitly as
            <Code Tag>Blazorise.ValidationSummary</Code>.
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="ValidationSummaryExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Auto Validation">
        By default form is auto-validated on page load. In case you want to disable it and validate
        only when user starts entering fields, now you can. Just set <Code>ValidateOnLoad</Code> to false.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <AutoValidationExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="AutoValidationExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Validation rules">
        In Blazorise you can use some of the predefined validation rules. eg
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <ValidationRulesExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="ValidationRulesExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="IValidatableObject">
        This example demonstrates how to implement validation in a Blazor component using the <Code>IValidatableObject</Code> interface for custom logic. The form contains several fields bound to a CompanyInfo model, which is validated automatically using data annotations and custom validation logic.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <ValidationIValidatableObjectExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="ValidationIValidatableObjectExample" />
</DocsPageSection>

<DocsPageParagraph>
    List of the currently available validators.
</DocsPageParagraph>

<DocsMethods ShowReturnType="false" ShowParameters="false">
    <DocsMethodsItem Name="IsEmpty">
        Check if the string is null or empty.
    </DocsMethodsItem>
    <DocsMethodsItem Name="IsNotEmpty">
        Check if the string is not null or empty.
    </DocsMethodsItem>
    <DocsMethodsItem Name="IsEmail">
        Check if the string is an email.
    </DocsMethodsItem>
    <DocsMethodsItem Name="IsAlpha">
        Check if the string contains only letters (a-zA-Z).
    </DocsMethodsItem>
    <DocsMethodsItem Name="IsAlphanumeric">
        Check if the string contains only letters and numbers.
    </DocsMethodsItem>
    <DocsMethodsItem Name="IsAlphanumericWithUnderscore">
        Check if the string contains only letters, numbers and underscore.
    </DocsMethodsItem>
    <DocsMethodsItem Name="IsUppercase">
        Check if the string is uppercase.
    </DocsMethodsItem>
    <DocsMethodsItem Name="IsLowercase">
        Check if the string is lowercase.
    </DocsMethodsItem>
    <DocsMethodsItem Name="IsChecked">
        Checks if the boolean based input is checked.
    </DocsMethodsItem>
    <DocsMethodsItem Name="IsSelected">
        Checks if the selection based input has a valid value selected. Valid values are anything except for <Code>null</Code>, <Code>string.Empty</Code>, or <Code>0</Code>.
    </DocsMethodsItem>
    <DocsMethodsItem Name="IsFileSelected">
        Checks if the file is selected.
    </DocsMethodsItem>
</DocsMethods>

<ComponentApiDocs ComponentTypes="[typeof(Validations),typeof(Validation),typeof(ValidationError)]" />